Template Files

Overview
	This is just a brief introduction into using template files. It will
	tell you how to create a template file, discuss the special placeholders
	that you can use, and finish off looking at include files.


Introduction
	To help you create your HTML documents, you can design a basic skeleton
	HTML doucment that you can base your other documents on.
	
	The first thing that you may wish to do is to create a folder in
	which to store your template files. I would suggest that you create this
	in your BBEdit folder (but anywhere will do). Enclosed with this archive
	is a folder called 'Templates'. You can either just drag this straight
	to where you want your templates to live, or copy the files enclosed
	into a folder you have created.
	
	Now that we have a folder to hold our templates, we need to set the
	template file in the Preferences. Do this by opening the 'Utilities'
	tool, and clicking on the 'Preferences' button. Select 'Template' from
	the popup menu, and then click on the button. This will then ask you to
	locate the template file - so do just that.
	
	If you have a number of different templates for different jobs, just
	repeat this process when you want to change them.
	
Using a Template
	Now that you have set the template file, to create a document using that
	template, select the 'Document' tool. You will then have a window with a
	number of fields that you may or may not wish to fill in. You really
	must fill in the TITLE field, and I would strongly recommend that you
	fill in the BASE field as well. You now have the choice of either just
	creating a bare-bones document by clicking on 'OK', or using the
	template, by clicking on 'Insert Template'. If you wish to make 'Insert
	Template' the default button, you can option-click on it. (You can make
	'OK' the default again by option-clicking on it too.). If you have used
	the default template that came with this archive, then you should see
	some of the information that you filled into the fields appear in the
	newly created document, based on the template file. This is done with
	'placeholders'.
	
Placeholders
	You can include certain placeholders in your template file. These are
	strings that will be replaced by some appropriate text. For example, you
	may wish to add the current date, or user-name to the file, and this can
	easily be done using placeholders.
	
	Placeholder			Action
	===========			======
	#TITLE# 			the title of the document, as entered using the
						Document tool.
	#LINK#				The link as entered using the Document tool.
	#BASE#				The base as entered using the Document tool.
	#NEXTID#			The Next ID of the document.
	
	#THEUSERNAME#		The user name (from chooser/sharing)
	#THEMACHINE#		The machine name.
	#THEDATE#			The short date (eg xx/xx/xx)
	#THELONGDATE#		The long date (eg xx August 1994)
	#THETIME#			The time
	#THEROOT#			The root directory on the machine
	#THESERVER#			The URL of your server.
	#THEPREFIX#			The prefix to access your documents from the server.

Include Files
	Those of you who have used C and other programming languages will be
	familiar with include files. These are other files that can be included
	in the current file by using a reference to it (eg #include "test.html")
	Your HTML documents can therefore include other files, such as a header
	or footer file.
	
	The way the standard include file reference is processed is that the
	file will replace the reference to it. So if your template contains a
	reference to a footer, then you write
	
			#include "footer.html"
	
	When this template is used, this reference will be overwritten by the
	contents of the file.
	
	Now there will be some of you who will be disappointed by this. Surely
	if the #include statement is overwritten, then it won't be possible to
	update the document if you ever decide you want to change the contents
	of the footer.
	
	So what you really want is a way of ensuring that there is a reference
	to a file that stays in your document permanently. This raises the
	problem of how to have these file references in the document without
	fouling up the HTML for the user. My solution is to embed the include
	statement in an HTML comment. This way the user never sees it, but the
	reference remains in the document. The syntax is...
	
			<!-- #include "footer.html" -->
	
			<!-- end include -->
	
	Note that there is a closing comment. This is necessary because when the
	document is updated it needs to know which area of text can be replaced
	by the footer file. (In the event of the file not being found, a message
	to that effect will be inserted).
	
Location
	Now, these include files should be stored in the same folder as your
	template file, so that the tools can find them easily. You can create
	subfolders in the template folder if you wish, as long as you change the
	file reference accordingly, eg 
	
			#include ":Footers:myFooter.html"
			
	(take note of the colons).